home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Alles Voor Internet / Tout Pour Internet
/
alles voor internet.iso
/
MacInternet™
/
Telnet
/
NCSA
/
tn3270 2.3d26 source
/
tn3270
/
api.h
< prev
next >
Wrap
Text File
|
1991-06-12
|
20KB
|
513 lines
/* tn3270 API Interface */
/* This file defines the content of messages sent to or from the tn3270
API. These messages are sent using either the SPPC driver or the
PPC Toolbox in System 7 and later. Due to limitations of the SPPC
driver, the longest message cannot exceed 128 bytes. */
/* Note: all characters strings are C strings (null delimited). */
/* message type values */
#define ErrorResponseType 4001
#define GetIdRequestType 2
#define GetIdResponseType 4002
#define GetCapRequestType 3
#define GetCapResponseType 4003
#define GetVersRequestType 4
#define GetVersResponseType 4004
#define OpenRequestType 5
#define OpenResponseType 4005
#define GetConnStatusType 6
#define GetConnResponseType 4006
#define GetCharRequestType 7
#define GetCharResponseType 4007
#define CloseRequestType 8
#define CloseResponseType 4008
#define CloseNotifyRequestType 9
#define CloseNotifyResponseType 4009
#define CloseEventResponseType 4010
#define GetBuffersRequestType 11
#define GetBuffersResponseType 4011
#define WriteNotifyRequestType 12
#define WriteNotifyResponseType 4012
#define WriteEventResponseType 4013
#define SendDataRequestType 14
#define SendDataResponseType 4014
#define SendLocalRequestType 15
#define SendLocalResponseType 4015
/* error response codes */
#define noError 0
#define badMessageType 1
#define badRequestLength 2
#define unimplementedErr 3
/* response codes for connection status and open */
#define openResPending 10 /* name resolution in progress */
#define openResFailed 11 /* name resolution failed */
#define openConnPending 12 /* connection in progress */
#define openConnFailed 13 /* connection failed */
#define openNegOptions 14 /* option negotiation in progress */
#define openLineMode 15 /* connection opened in line mode */
#define open3270Mode 16 /* connection opened in 3270 mode */
#define openNoSessions 17 /* no more sessions available */
#define openFormatErr 18 /* invalid screen format specified */
#define openBadId 19 /* (status) no conn. record for msgid */
/* response codes for close notification request */
#define closeNotifyActive 30 /* close notification already active */
/* close event codes */
#define closeNetFail 31 /* network failure */
#define closeNetClose 32 /* network connection closed */
#define closeAPI 33 /* API request */
#define closeUser 34 /* user action */
#define closeUnknown 35 /* undetermined */
/* response codes for write notification request */
#define writeNotifyActive 40 /* write notification already active */
/* response codes for send data and send local request */
#define sendLocked 50 /* send rejected- keyboard is locked */
#define sendBadAddress 51 /* cursor address is invalid */
#define sendInsErr 52 /* no room for char. in insert mode */
#define sendAttrErr 53 /* attempt to overwrite attr. byte */
#define sendProtErr 54 /* attempt to store in protected field */
#define sendAIDErr 55 /* invalid AID code specified */
#define sendFmtErr 56 /* invalid for unformatted screen */
#define sendOpErr 57 /* invalid op code for send local */
/* API calls for the Session Manager */
/* The session manager is called to create new sessions. Once a
session is created, all subsequent API calls are made to the
session itself. For SPPC, the session manager registers itself
as "GFTMn", where "n" is a digit from 1 through 8. For PPC,
the session manger registers itself as "tn3270 #n". This form
of registration allows multiple copies of tn3270 to be running
at the same time. "n" will be the lowest number not already
in use at the time tn3270 is launched. */
/* Session Manager: Error Response
If the session manager receives a message type it cannot
identify, or a request which cannot be executed for some
reason, it returns an error response structure: */
typedef struct {
short msgtype; /* ErrorResponseType */
short code; /* error code */
} ErrorResponse;
/* Session Manager: Get Id
This call returns the signature, name, and reference number of the
tn3270 application. The name allows the API client to identify the
application by the same name the user has assigned to it. */
typedef struct {
short msgtype; /* GetIdRequestType */
} GetIdRequest;
typedef struct {
short msgtype; /* GetIdResponseType */
OSType signature; /* 4-character application signature */
/* "GFTM" for standard tn3270 */
short refnum; /* app. resource file refnum */
unsigned char appname[120]; /* application file name */
} GetIdResponse;
/* Session Manager: GetCapabilities
This call returns information describing the valid parameters
for creating new sessions. The client sends a GetCapRequest
structure, and the API returns a GetCapResponse structure: */
typedef struct {
short msgtype; /* GetCapRequestType */
} GetCapRequest;
typedef struct {
short ptsize; /* point size */
short rows; /* number of rows */
short cols; /* number of columns */
} screenformat;
typedef struct {
short msgtype; /* GetCapResponseType */
short pendsessions; /* current number of pending sessions */
short currsessions; /* current number of opened sessions */
short maxsessions; /* maximum number of sessions */
short numbformats; /* number of screen formats which follow */
screenformat sizeinfo[2]; /* max. dimensions for each pointsize */
} GetCapResponse;
/* Session Manager: GetVersion
This call returns the contents of tn3270's 'vers' 1 resource. The
client sends a GetVersRequest structure, and the API returns a
GetVersResponse structure. If the 'vers' 1 resource is not available
for some reason, the "verssize" field of the response will be set
to zero. */
typedef struct {
short msgtype; /* GetVersRequestType */
} GetVersRequest;
typedef struct {
short msgtype; /* GetVersResponseType */
short verssize; /* size of 'vers' 1 resource */
unsigned char versdata[120]; /* contents of 'vers' 1 resource
(actual size given by "verssize") */
} GetVersResponse;
/* Session Manager: OpenSession
This call creates a new session according to the parameters in
the OpenRequest structure. The session manager returns an
OpenResponse structure when the open suceeds, or has failed for
some reason. Due to network conditions, it may take as long as
several minutes before a response is generated.
Storage for the hostname and windowname strings may be released
once the OpenResponse is received. */
typedef struct {
short msgtype; /* OpenRequestType */
unsigned char *hostname; /* host name to connect to,
maximum length = 255 */
unsigned char *windowname; /* name for new window,
maximum length = 127 */
screenformat dfltsize; /* default screen size (24 by 80) */
screenformat altsize; /* alternate screen size */
char hide; /* true if window should be hidden */
char nowsf; /* true to suppress WSF support */
char noalert; /* true to suppress alerts to user */
} OpenRequest;
typedef struct {
short msgtype; /* OpenResponseType */
short code; /* error code (or noError) for open */
short sppcrefnum; /* SPPC refnum for new session */
short ppcportnum; /* PPC portRefNum for new session */
unsigned char sppcname[9]; /* SPPC name for new session */
unsigned char ppcname[21]; /* PPC name for new session */
} OpenResponse;
/* Session Manager: GetConnectionStatus
This call returns the status of a pending connection. A
connection is pending when an open request has been made for
the connection, but an open response has not been generated
yet. */
typedef struct {
short msgtype; /* GetConnStatusType */
unsigned long openid; /* message id of session open request */
} GetConnStatus;
typedef struct {
short msgtype; /* GetConnResponseType */
unsigned long openid; /* openid from GetConnStatus */
short statuscode; /* code for connection status */
} GetConnResponse;
/* API Calls for Sessions */
/* For SPPC, each session registers itself as "GFTMn-i", where
"GFTMn" is the same as the session manager registration, and
"i" is a digit from 1 through 8. For PPC, each session registers
itself as "tn3270 #n session i". "i" will be the lowest number
not already in use at the time the session is created. */
/* Sessions: Error Response
The error response for a session is the same as for the session
manager. (See above.)
*/
/* Sessions: GetCharacteristics
This call returns the characteristics of a session. The client
sends a GetCharRequest message, and the API responds with a
GetCharResponse structure: */
typedef struct {
short msgtype; /* GetCharRequestType */
unsigned char *hostname; /* pointer to storage for hostname */
/* must be 256 bytes (or more) */
unsigned char *windowname; /* pointer to storage for windowname */
/* must be 128 bytes (or more) */
} GetCharRequest;
typedef struct {
short msgtype; /* GetCharResponseType */
screenformat dfltsize; /* default screen size (24 by 80) */
screenformat altsize; /* alternate screen size */
char linemode; /* true for a line mode session */
char hide; /* true if window is hidden */
char nowsf; /* true if WSF suppression was requested */
char noalert; /* true if user alerts suppressed */
} GetCharResponse;
/* Sessions: Close
This calls requests that a session be closed. The client sends
a CloseRequest structure, and the API responds with a CloseResponse
structure.
NOTE: tn3270 will not delay session close processing until the
response to the close request is read by the client. Since session
close processing includes deregistering the session, when a close
is successful, in some cases the close response may never be
received. However, this has never occurred during testing.
*/
typedef struct {
short msgtype; /* CloseRequestType */
} CloseRequest;
typedef struct {
short msgtype; /* CloseResponseType */
short code; /* error code (or noError) for close */
} CloseResponse;
/* Sessions: CloseNotification
This call allows a client to request notification when a session
closes. Notification will occur when a session closes due to a
client's close request, and also when the session closes for other
reasons, such as a network problem, or action taken by the user.
The client sends a CloseNotifyRequest structure, and
receives a CloseNotifyResponse structure from the API. In addition,
the client may, at some time in the future, receive a
CloseEventResponse structure when the session closes.
Only one client may be defined to receive close notification for a
connection at any given time.
Notification may be reset at any time. It is not an error to
reset notification when it has never been set.
NOTE: tn3270 will not delay session close processing until the
close notification is read by the client. Since session
close processing includes deregistering the session, when a close
is successful, in some cases the close notification may never be
received. However, this has never occurred during testing. */
typedef struct {
short msgtype; /* CloseNotifyRequestType */
char notifyflag; /* true to set, false to reset notify */
} CloseNotifyRequest;
typedef struct {
short msgtype; /* CloseNotifyResponseType */
short code; /* error code (or noError) for request */
} CloseNotifyResponse;
typedef struct {
short msgtype; /* CloseEventResponseType */
short sppcrefnum; /* SPPC refnum for connection */
short ppcportnum; /* PPC portRefNum for connection */
short code; /* error code for cause of close */
} CloseEventResponse;
/* Sessions: GetBuffers
This call allows a client to obtain the addresses of tn3270's
data and attribute buffers. The addresses of the internal
variables "kblock" and "kblcode" are returned, which indicate
whether and why the keyboard is locked. Also, the address of
the internal variable "curadr" is returned, which contains the
cursor position.
NOTE: The buffer addresses are provided to allow efficient
examination of the buffers. This call is not intended to
allow the client to modify the buffers or variables, and
any such use is unsupported. The effect of modifying
these data structures is unpredictable, and may change
in different versions of tn3270. Use SendDataRequest
described below to update the buffers.
The data buffer contains the data received in 3270 data streams,
and consists of one byte for each character position.
The data is EBCDIC as received from the host, without being
translated. X'1D' is stored in buffer positions corresponding
to field attributes (created by either the Start Field or
Start Field Extended orders). However, the most reliable way
to test for a field attribute is to examine bit 15 of the
attribute bits (see below).
The attribute buffer contains attribute information for each
data character, and consists of 16 bits for each character
position. The bits are defined as follows (bit 15 is the most
significant bit):
bit 15: 0 = data at this screen position
1 = attribute byte at this screen position
bit 14: 0 = GE does not apply to this character
1 = GE does apply to this character
bits 13-8: For field attributes, these are the bits 5-0 (the
least significant 6 bits) of the field attribute.
bits 7-6: Character set for the character or field. 00 is the
default character set; 01 is the APL/Text character
set. Other values are currently undefined, and
map to the default character set.
bit 5: Selection bit: set if this character is included
in text selection (as done with the mouse).
bits 4-3: Extended highlighting:
00 = none
01 = blink
10 = reverse
11 = underscore
bits 2-0: Color:
000 = default (green)
001 = blue
010 = red
011 = pink
100 = green
101 = turquoise
110 = yellow
111 = white
"kblock" is a single byte which is 0 when the keyboard is
unlocked, and 1 when the keyboard is locked.
"kblcode" is a single byte with the following definition:
0 = keyboard is unlocked
1 = keyboard is locked: last write from host did not
unlock the keyboard
2 = keyboard is locked: waiting for host to respond
to last read response transmitted
3 = keyboard is locked due to communications error
4 = keyboard is locked due to no active session (should
not happen during API use)
"curadr" is the screen offset of the cursor. It is a 16-bit
unsigned integer.
*/
typedef struct {
short msgtype; /* GetBuffersRequestType */
} GetBuffersRequest;
typedef struct {
short msgtype; /* GetBuffersResponseType */
unsigned char *databuff; /* data buffer pointer */
unsigned short *attrbuff; /* attribute buffer pointer */
unsigned char *kblock; /* address of "kblock" */
unsigned char *kblcode; /* address of "kblcode" */
unsigned short *curadr; /* address of "curadr" */
} GetBuffersResponse;
/* Sessions: WriteNotification
This call allows the client to request notification of changes
to the data and attribute buffers. Notification will occur
when any changes to the buffer contents are made due to write
commands received from the host. Notification will also occur
when the host issues a read command. Notification will not occur
when changes are made due to API or user-entered screen updates.
Only one client may be defined to receive write notification for
a connection at any given time. */
typedef struct {
short msgtype; /* WriteNotifyRequestType */
char notifyflag; /* true to set, false to reset notify */
} WriteNotifyRequest;
typedef struct {
short msgtype; /* WriteNotifyResponseType */
short code; /* error code (or noError) for request */
} WriteNotifyResponse;
typedef struct {
short msgtype; /* WriteEventResponseType */
short sppcrefnum; /* SPPC refnum for connection */
short ppcportnum; /* PPC portRefNum for connection */
unsigned char ccwop; /* CCW op-code for this operation */
/* or 0 for line mode write */
} WriteEventResponse;
/* Sessions: SendData
SendData allows the client to do any of the following, in order:
(1) set the current cursor address
(2) modify the data and attribute buffers
(3) send screen modifications to the host, with a specified
AID code. An appropriate data stream for the given AID
code will be generated.
Data will be entered into the data buffer exactly as specified
in the data field, starting at the cursor address. The cursor
address will then be updated following the same rules as for
user input. Graphics Escape (GE) may be specified for a character
by preceding it by GE (X'08') in the data. GE will never be stored
in the buffer, and is not included in the returned count of stored
characters.
If the keyboard is locked, all three operations will be skipped,
and the response code "sendLocked" will be returned.
If the cursor address is invalid, all three operations will be
skipped, and the response code "sendBadAddress" will be returned.
If a data character cannot be stored, the "code" field of the
response will indicate the type of error, and the "count" field
will contain the number of characters successfully stored. Also,
any AID code specified will not be transmitted.
If an invalid AID code is specified, no AID code will be sent,
and the "code" field of the response will contain an error code.
For line mode sessions, steps 1 and 3 are skipped, and the data
consists of ASCII characters to be sent to the host. In this case,
no errors are returned. */
typedef struct {
short msgtype; /* SendDataRequestType */
unsigned short curadr; /* cursor address (screen offset),
or 65535 (-1) to leave unchanged */
unsigned char aidcode; /* AID code to send, or 0 to skip */
unsigned char spare; /* unused- set to 0 */
short length; /* length of data to store, or 0
to skip */
unsigned char data[120]; /* data to store */
} SendDataRequest;
typedef struct {
short msgtype; /* SendDataResponseType */
short code; /* response code (or noError) */
short count; /* number of characters stored */
unsigned short curadr; /* ending cursor address */
} SendDataResponse;
/* Sessions: SendLocal allows the client to perform a local terminal
operation. A sequence of operation codes is sent in the data
field of the request. If the keyboard is locked, SendLocal will
be rejected with the response code "sendLocked". However, an
exception is that "reset" as the first local operation specified
will unlock the keyboard. If an operation produces an error,
subsequent operations will not be performed. The "code" field
in the response will indicated the type of error, and the "count"
field will indicate the number of completed operations.
The operation codes are:
1 cursor up
2 cursor down
3 cursor left
4 cursor right
5 tab
6 backtab
7 newline
8 home
9 erase eof
10 erase input
11 toggle insert mode
12 delete character
13 reset keyboard
14 dup
15 field mark
16 toggle APL mode
17 insert blank
18 rubout
19 cursor up twice
20 cursor down twice
21 cursor left twice
22 cursor right twice
23 toggle cursor position display
*/
typedef struct {
short msgtype; /* SendLocalRequestType */
short length; /* length of data field */
long spare; /* unused- set to zero */
unsigned char data[120]; /* list of operation codes */
} SendLocalRequest;
typedef struct {
short msgtype; /* SendLocalResponseType */
short code; /* response code (or noError) */
short count; /* count of op codes executed */
unsigned short curadr; /* ending cursor address */
} SendLocalResponse;